<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Managing connections to ECLiPSe
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot047.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc97">8.7</A>&nbsp;&nbsp;Managing connections to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP></H2><UL>
<LI><A HREF="embroot048.html#toc54">A unified ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-side interface to Java : the `peer' concept</A>
<LI><A HREF="embroot048.html#toc55">Creating and managing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engines from Java</A>
<LI><A HREF="embroot048.html#toc56">Connecting to an existing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine using <I>RemoteEclipse</I></A>
<LI><A HREF="embroot048.html#toc57">Comparison of different Java-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> connection techniques</A>
</UL>

<A NAME="sec:ji-managing-eclipse-connections"></A>
As of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> 5.3 and later, there are three Java classes which can be
used to provide interaction with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. These are <I>EmbeddedEclipse</I><A NAME="@default262"></A>, <I>OutOfProcessEclipse</I><A NAME="@default263"></A>
and <I>RemoteEclipse</I><A NAME="@default264"></A>. Although the three
classes all implement the <I>EclipseConnection</I> <A NAME="@default265"></A> interface, there are some important differences in
initialisation, termination and use which are explained in this section. On
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, as of version 5.3 and later, there is a unified
interface for interaction with Java, based around the concept of a
`peer'. This is explained in Section
<A HREF="#sec:ji-peer-concept">8.7.1</A>. Section
<A HREF="#sec:ji-creating-eclipse-engines">8.7.2</A> discusses how to create an
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine from within Java (this covers both <I>EmbeddedEclipse</I> and <I>OutOfProcessEclipse</I><A NAME="@default266"></A>). Section
<A HREF="#sec:ji-connecting-existing">8.7.3</A> discusses the <I>RemoteEclipse</I>
class, which allows Java to connect to an existing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
engine. Finally, Section <A HREF="#sec:ji-compare-connection-classes">8.7.4</A>
compares the three connection classes, assessing the advantages and
disadvantages of each.<BR>
<BR>
<A NAME="toc54"></A>
<H3 CLASS="subsection"><A NAME="htoc98">8.7.1</A>&nbsp;&nbsp;A unified ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-side interface to Java : the `peer' concept</H3>
<A NAME="sec:ji-peer-concept"></A>
To allow ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code to be independent of the way it is
interfacing with Java, there is a unified technique in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> for
interfacing to Java and other non-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> programs, based on the
concept of a <I>peer</I>. A peer is a computation environment which is
external to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, either in the sense of being a different
computer language or being a different process, possibly on a
different machine. When ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is communicating with one or more
Java virtual machines using the Java-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> interface (including
cases where ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is embedded), it stores some global information
to keep track of each peer.<BR>
<BR>
Each peer of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine is indexed within ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
by a unique <I>peer name</I> which is an atom. This is set during the
initialisation of the connection between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java; the
details vary according to the Java class used to make the connection.<BR>
<BR>
The peer name is used in those ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> predicate calls related to the
peer connection. In particular, those related to the opening and closing of
peer queues (see Section <A HREF="embroot046.html#sec:ji-open-close">8.5.1</A>). The <I>EclipseConnection</I> <A NAME="@default267"></A> interface includes
the method <TT>getPeerName()</TT> which can be used to retrieve this name on
the Java side.<BR>
<BR>
<A NAME="toc55"></A>
<H3 CLASS="subsection"><A NAME="htoc99">8.7.2</A>&nbsp;&nbsp;Creating and managing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engines from Java</H3>
<A NAME="sec:ji-creating-eclipse-engines"></A>
There are at present two options for creating an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine from
Java. With <I>EmbeddedEclipse</I><A NAME="@default268"></A>, the engine
takes the form of a dynamically loaded shared library within the Java
virtual machine. With <I>OutOfProcessEclipse</I><A NAME="@default269"></A> it is a separate, child
process of the Java virtual machine. These two options have in common that
they are both initialised using an <I>EclipseEngineOptions</I> object and
that both classes implement <I>EclipseEngine</I> <A NAME="@default270"></A>.<BR>
<BR>

<H4 CLASS="subsubsection">Configuring an <I>EclipseEngineOptions</I> object</H4>
<A NAME="sec:ji-eclipse-engine-options"></A>
Before an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine is created using either option, an <I>EclipseEngineOptions</I> object must be created and configured. An
instance of the <I>EclipseEngineOptions</I> class represents our
configuration choices for a new ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine. <BR>
<BR>
The options can be specified by either looking them up in a <I>java.util.Properties</I> instance or by calling &#8220;set&#8221; methods on the
<I>EclipseEngineOptions</I> instance.<BR>
<BR>
In the first case you can either specify system properties (by passing
<TT>-D</TT> command line options to the JVM) or you can use an <I>EclipseEngineOptions</I> constructor which takes a <I>Properties</I>
parameter. Each option has a standard property name detailed below.<BR>
<BR>
Once the <I>EclipseEngineOptions</I> object is created, there are
also &#8220;set&#8221; methods we can invoke on it to set the different options.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>The ECL</B><SUP><B><I>i</I></B></SUP><B>PS</B><SUP><B><I>e</I></B></SUP><B> installation directory (<TT>eclipse.directory</TT>)</B><DD CLASS="dd-description"> This must be the correct path of an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
installation so that Java can find the files it needs to start
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. If an <I>EclipseEngineOptions</I> constructor is invoked
without a directory having been set, either using a constructor
parameter or as a property, an exception will be thrown.<BR>
<BR>
<DT CLASS="dt-description"><B>The default module (<TT>eclipse.default-module</TT>)</B><DD CLASS="dd-description"> is the
default ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> module where goals are executed. If no setting is
made, then the default module will be &#8220;eclipse&#8221;.<BR>
<BR>
<DT CLASS="dt-description"><B>Local and global size (<TT>eclipse.local-size</TT> and <TT>eclipse.global-size</TT>)</B><DD CLASS="dd-description">
are the maximum size of the local stack and the global stack
respectively. In each case the option is an integer representing the
required size in megabytes. If no setting is made, the sizes default
to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> defaults.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> 
<B>Local size</B><DD CLASS="dd-description"> is the maximum combined size of the local 
 stack and the control stack. Roughly speaking, the local stack is
 the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> equivalent of the call/return stack in procedural
 languages. The control stack is used to store the choicepoints which
 occur in the execution of non-deterministic code. You may therefore
 need to increase this limit if your search tree is exceptionally
 deep or if there is a lot of non-determinism. You can use the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal
 <TT>get_flag(max_local_control, X)</TT> to find out the current
 setting. For more details, see the section on &#8220;Memory Organisation
 and Garbage Collection&#8221; in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> User Manual.
<DT CLASS="dt-description"><B>Global size</B><DD CLASS="dd-description"> is the maximum combined size of the global 
 stack and the trail stack. The global stack is used to store data
 structures. The trail stack is used to store backtracking
 information and is therefore closely related to the control
 stack. You may need to increase this limit if you are creating large
 data structures in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, or if there is a lot of
 non-determinism. You can use the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal <TT>get_flag(max_global_trail, X)</TT> to find out the current
 setting. Again, see the section in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> User Manual for
 more details.
</DL><BR>
<BR>
<DT CLASS="dt-description"><B>The &#8220;use queues&#8221; flag (<TT>eclipse.use-queues</TT>)</B><DD CLASS="dd-description">
<A NAME="sec:ji-use-queues-flag"></A> If <TT>false</TT> (the default case), the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine's standard streams (<TT>stdin</TT>, <TT>stdout</TT> and
<TT>stderr</TT>) will be connected to the standard streams of the JVM. So
for example if, as in <TT>QuickTest.java</TT>, a message is written to
<TT>stdout</TT> from within ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, this will appear on the <TT>stdout</TT> stream of the JVM. Similarly, if ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> requests input
from the <TT>stdin</TT> stream, input will be requested from the <TT>stdin</TT> stream of the JVM. If the flag is set <TT>true</TT>, <I>FromEclipseQueue</I> and <I>ToEclipseQueue</I> objects are used to
represent the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s standard streams.<BR>
<BR>
<DT CLASS="dt-description"><B>The peer name (<TT>eclipse.peer-name</TT>)</B><DD CLASS="dd-description"> is the peer name by
which the Java side can be referenced within ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, for example when
queues are created from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. By default the peer name for
the Java side when using an <I>EmbeddedEclipse</I><A NAME="@default271"></A> or an <I>OutOfProcessEclipse</I><A NAME="@default272"></A> is &#8220;host&#8221;.</DL>

<H4 CLASS="subsubsection">Using <I>EmbeddedEclipse</I></H4>
<A NAME="@default273"></A>This section discusses issues specific to using the <I>EmbeddedEclipse</I> class. With <I>EmbeddedEclipse</I>, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine
is a dynamically loaded native library in the Java virtual machine. Figure
<A HREF="#fig:ji-embedded-deployment">8.1</A> shows this deployment model in UML
notation. The important consequences of this deployment model are:
<UL CLASS="itemize"><LI CLASS="li-itemize">
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine shares memory and other resources with Java. 
<LI CLASS="li-itemize">Only one such engine can exist in a Java virtual machine at any one time.
<LI CLASS="li-itemize">Communication between Java and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is very efficient.
</UL><BR>
<BR>
<DIV CLASS="center">
 <BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
 <DIV CLASS="center">
 <IMG SRC="embroot001.gif">
 </DIV>
 <BR>
<BR>
<DIV CLASS="center">Figure 8.1: <A NAME="fig:ji-embedded-deployment"></A>UML deployment diagram for <I>EmbeddedEclipse</I></DIV><BR>
<BR>

 <DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
</DIV><BR>
<BR>

<H5 CLASS="paragraph">Initialising an <I>EmbeddedEclipse</I></H5>
The embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> which runs within the JVM and shares its
resources, can be started and ended only once during the lifetime of
the JVM. There is no public constructor method for <I>EmbeddedEclipse</I>. Initialisation of the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is done
using the static <TT>getInstance</TT> method of class <I>EmbeddedEclipse</I> which takes an <I>EclipseEngineOptions</I> instance as
a parameter. The method uses this to configure and set up ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
and then returns an object of type <I>EmbeddedEclipse</I>. There may
only ever be one instance of <I>EmbeddedEclipse</I> in a JVM. If the
embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> has already been set up or if it has been set up
and terminated, subsequent invocations of <TT>getEclipse</TT> with an
<I>EclipseEngineOptions</I> will throw exceptions. However during the
lifetime of the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, a reference to the unique <I>EmbeddedEclipse</I> object can be obtained using the parameterless static
<TT>getEclipse</TT> method.<BR>
<BR>

<H5 CLASS="paragraph">Termination of an <I>EmbeddedEclipse</I></H5>
The <TT>destroy</TT> method which appears in the <I>EmbeddedEclipse</I>
class will shut the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> down. Once the <TT>destroy</TT>
method has been invoked, the invocation of any methods which require
use of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine will result in an <I>EclipseTerminatedException</I> being thrown. The <TT>destroy</TT> method
should free all the resources of the JVM process which were being used
by the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
Once the <I>EmbeddedEclipse</I> has been destroyed, <TT>getEclipse</TT>
can no longer be used during the lifetime of the JVM to initialise an
embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine. In other words, by invoking <TT>destroy</TT>,
one removes the ability to use embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engines within the
current instance of the JVM.<BR>
<BR>

<H4 CLASS="subsubsection">Using <I>OutOfProcessEclipse</I><A NAME="@default274"></A></H4>
This section discusses issues specific to the <I>OutOfProcessEclipse</I><A NAME="@default275"></A> class. With <I>OutOfProcessEclipse</I>, the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine is a child process of the Java virtual
machine. Figure <A HREF="#fig:ji-outOfProcess-deployment">8.2</A> shows this deployment
model in UML notation. The important consequences of this deployment
model are:
<UL CLASS="itemize"><LI CLASS="li-itemize">
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine uses separate memory and other resources, 
depending on how the operating system allocates these between processes. 
<LI CLASS="li-itemize">Several instances of <I>OutOfProcessEclipse</I><A NAME="@default276"></A> can exist in a Java 
virtual machine at any one time.
<LI CLASS="li-itemize">Communication between Java and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is less efficient.
</UL><BR>
<BR>
<DIV CLASS="center">
 <BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> 
 <DIV CLASS="center"> 
 <IMG SRC="embroot002.gif">
 </DIV>
 <BR>
<BR>
<DIV CLASS="center">Figure 8.2: <A NAME="fig:ji-outOfProcess-deployment"></A>UML deployment
 diagram for <I>OutOfProcessEclipse</I></DIV><BR>
<BR>
 <DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
</DIV><BR>
<BR>

<H5 CLASS="paragraph">Initialisation of an <I>OutOfProcessEclipse</I><A NAME="@default277"></A></H5>
<I>OutOfProcessEclipse</I><A NAME="@default278"></A> has a single constructor which takes an <I>EclipseEngineOptions</I> object as its only parameter. See Section
<A HREF="#sec:ji-eclipse-engine-options">8.7.2</A> for details of how to create and
configure this object. Unlike <I>EmbeddedEclipse</I>, multiple <I>OutOfProcessEclipse</I><A NAME="@default279"></A> instances are allowed.<BR>
<BR>

<H5 CLASS="paragraph">Termination of an <I>OutOfProcessEclipse</I></H5>
We invoke the instance method <TT>destroy()</TT> in <I>OutOfProcessEclipse</I><A NAME="@default280"></A> to terminate both the child ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process
and our association with it. Once the <TT>destroy</TT> method has been
invoked, the invocation of any methods on the destroyed <I>OutOfProcessEclipse</I> object which require use of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine will
throw an <I>EclipseTerminatedException</I>. Unlike <I>EmbeddedEclipse</I>, invoking <TT>destroy()</TT> on an <I>OutOfProcessEclipse</I> does not affect our ability to create new <I>OutOfProcessEclipse</I> instances during the lifetime of the Java virtual
machine.<BR>
<BR>
If the child process ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> crashes or is killed while ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
has control, the Java thread which handed control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> should
throw an <I>EclipseTerminatedException</I>. If this happens while Java
has control, usually the next invocation of a method on the <I>OutOfProcesEclipse</I> should throw an <I>EclipseTerminatedException</I>,
although it is possible that some operations will throw a different
class of <I>IOException</I>. If this should happen it is worth calling
the <TT>destroy</TT> method to do a final clean-up.<BR>
<BR>
<A NAME="toc56"></A>
<H3 CLASS="subsection"><A NAME="htoc100">8.7.3</A>&nbsp;&nbsp;Connecting to an existing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine using <I>RemoteEclipse</I><A NAME="@default281"></A></H3>
<A NAME="sec:ji-connecting-existing"></A>
In some applications, for example where Java is used to visualise
search in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, the life of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine may begin
before the connection with Java is initialised or end after the
connection with Java is terminated. Furthermore, it may also be useful
for the eclipse engine and the Java virtual machine to be running on
physically separate computers, for example if the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> tasks are
being executed on a compute server, but the Java program is to be run
on a workstation. The <I>RemoteEclipse</I><A NAME="@default282"></A> class can be used to connect
Java to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> in these two scenarios. The deployment model is
that the <I>RemoteEclipse</I><A NAME="@default283"></A> Java object is a &#8220;Proxy&#8221; for the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine which is running on the remote machine, as shown in
UML notation in Figure <A HREF="#fig:ji-remote-deployment">8.3</A>.<BR>
<BR>
<DIV CLASS="center">
 <BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
 <DIV CLASS="center">
 <IMG SRC="embroot003.gif">
 </DIV>
 <BR>
<BR>
<DIV CLASS="center">Figure 8.3: <A NAME="fig:ji-remote-deployment"></A>UML deployment diagram for <I>RemoteEclipse</I></DIV><BR>
<BR>

 <DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
</DIV><BR>
<BR>
The key consequences of this deployment model are:
<UL CLASS="itemize"><LI CLASS="li-itemize">
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java can run on different machines and the two machines may have a different architecture/OS. 
<LI CLASS="li-itemize">ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can connect to multiple Java processes using this model.
<LI CLASS="li-itemize">The lifetime of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine need not necessarily be a sub-duration of the lifetime of the JVM. 
</UL>

<H4 CLASS="subsubsection">Initialisation of a <I>RemoteEclipse</I><A NAME="@default284"></A> connection</H4>
<A NAME="sec:ji-remote-init"></A>
Connecting Java to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> using <I>RemoteEclipse</I> requires the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine to be primed so that it is ready to accept the
connection. By the time it connects, the Java program must have the
IP address of the machine hosting the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine (the server)
and the port number being used for the connection. The attachment
protocol also optionally allows for a password to be used by the Java
side and checked against one specified on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. Also
the server must be configured to allow TCP/IP socket servers which can
be connected to by the machine hosting Java. Initialising a connection
using <I>RemoteEclipse</I><A NAME="@default285"></A> therefore requires some coordination between
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code and the Java code. The Java code always consists
of a single <I>RemoteEclipse</I> constructor invocation, although the
constructor parameters may vary. <BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side of the code uses certain builtins. Refer to the
relevant documentation of these for precise details of usage. On the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, the code can be structured in two different ways; one
simpler and the other allowing more flexibility. We outline here the
sequence of actions in each case.<BR>
<BR>

<H5 CLASS="paragraph">Basic connection sequence</H5>
This can be used in situations where no password is to be used and
where the port number is specified in advance, rather than generated
dynamically by ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, and is known by the Java side.
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
 The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side executes the builtin <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default286"></A>, specifying the port number in advance. This
	builtin will block until the connection is established. <BR>
<BR>
<LI CLASS="li-enumerate">The Java side then invokes one of the <I>RemoteEclipse</I><A NAME="@default287"></A>
	constructors which has no password parameter. This should
	immediately complete or throw an exception if the connection
	is unsuccessful.</OL>


<H5 CLASS="paragraph">Advanced connection sequence</H5>
This more complicated sequence uses a password and optionally allows
the port number to be generated dynamically and then communicated to
the Java side.
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
 The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side executes the builtin <A HREF="../bips/kernel/externals/remote_connect_setup-3.html"><B>remote_connect_setup/3</B></A><A NAME="@default288"></A>, specifying the password and either
	specifying the port number or allowing it to be generated
	dynamically.<BR>
<BR>
<LI CLASS="li-enumerate">The port number must be communicated to the Java side somehow,
 	e.g. manually, or via a file.<BR>
<BR>
<LI CLASS="li-enumerate">The Java side then invokes one of the <I>RemoteEclipse</I><A NAME="@default289"></A>
	constructors with a password parameter. This either blocks
	until the connection is successful or throws an exception.<BR>
<BR>
<LI CLASS="li-enumerate">The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side executes the builtin <A HREF="../bips/kernel/externals/remote_connect_accept-6.html"><B>remote_connect_accept/6</B></A><A NAME="@default290"></A>, specifying the password which the
 	Java should supply.<BR>
<BR>
<LI CLASS="li-enumerate">The Java constructor invocation then completes, or throws an
	exception if the connection could not be made.
</OL>
If left as a free variable, the <TT>Host</TT> argument of either the <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default291"></A> or <A HREF="../bips/kernel/externals/remote_connect_setup-3.html"><B>remote_connect_setup/3</B></A><A NAME="@default292"></A> goal will become
instantiated to the IP address of the machine hosting
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Another possibility is to call the goal with this argument
already instantiated to the atom <TT>localhost</TT>. This will mean that
only client connections made by processes on the same machine and
using the loopback address will be accepted. With this usage, on the
Java side you should use invoke <TT>InetAddress.getHostByName("localhost")</TT>. Note that <TT>InetAddress.getLocalHost()</TT> will not work in this situation.<BR>
<BR>
In both connection sequences, the peer name indexing the connection is
either specified or generated dynamically on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side in
the <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default293"></A> or <A HREF="../bips/kernel/externals/remote_connect_setup-3.html"><B>remote_connect_setup/3</B></A><A NAME="@default294"></A> goal.<BR>
<BR>
Once the connection has been established by one of the above
sequences, control initially rests with the Java side. Therefore the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code which called the <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default295"></A> goal or the
<A HREF="../bips/kernel/externals/remote_connect_accept-6.html"><B>remote_connect_accept/6</B></A><A NAME="@default296"></A> goal blocks until the Java side
explicitly transfers control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> or disconnects.<BR>
<BR>

<H4 CLASS="subsubsection">Explicit transfer of control between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java</H4>
<A NAME="sec:ji-remote-control-transfer"></A>
As mentioned above, after the initial connection has been established,
Java has control by default. However, this may not be convenient. For
example, in the case of search visualisation, after the initialisation
of the visualisation client, we may prefer ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to have control
by default, allowing control to pass to Java only on certain
occasions. Control can be explicitly passed from Java to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> by
invoking the <TT>resume()</TT> method on a <I>RemoteEclipse</I><A NAME="@default297"></A>. In this
case the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code will resume execution after the last point where
it passed control to Java. For example, if <TT>resume()</TT> is invoked
immediately after the <I>RemoteEclipse</I><A NAME="@default298"></A> constructor completes,
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution will resume at the point just after the call to
the <A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default299"></A> goal or the <A HREF="../bips/kernel/externals/remote_connect_accept-6.html"><B>remote_connect_accept/6</B></A><A NAME="@default300"></A>
goal.<BR>
<BR>
Control can be transferred to a Java peer using the <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default301"></A>
builtin. In this case the Java thread which passed execution to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will resume execution at the point where it blocked.<BR>
<BR>
The <TT>resume()</TT> method and the <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default302"></A> builtin should be
used with care. An invocation of <TT>resume()</TT> should be paired with
an execution of a <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default303"></A> goal in most cases. In addition,
<A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default304"></A> should not be executed in any code executed as a
result of an <TT>rpc</TT><A NAME="@default305"></A> invocation and <TT>resume()</TT> should not be
executed within the <I>QueueListener</I> methods <TT>dataAvailable()</TT>
or <TT>dataRequest()</TT>.<BR>
<BR>
The <TT>resume()</TT> method and the <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default306"></A> builtin should
only be used when other techniques such as <TT>rpc</TT><A NAME="@default307"></A> are not suitable.<BR>
<BR>

<H4 CLASS="subsubsection">Termination of a <I>RemoteEclipse</I> connection</H4>
<A NAME="sec:ji-remote-disconnect"></A>
A <I>RemoteEclipse</I><A NAME="@default308"></A> connection between ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and Java may be
terminated in different ways. Firstly, disconnection may be initiated
by either side. Secondly the disconnection may be either <I>multilateral</I> or <I>unilateral</I>. Multilateral disconnection, the
preferred method, is where the side which has control initiates
disconnection. Unilateral disconnection is where the side which
initiates disconnection does not have control, and should only take
place as a clean-up routine when one side is forced to terminate the
connection because of an unexpected event.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
 <B>Java-initiated multilateral disconnect</B><DD CLASS="dd-description"> is performed by
 invoking the <TT>disconnect</TT> method on the <I>RemoteEclipse</I><A NAME="@default309"></A>
 instance while the Java side has control.<BR>
<BR>
<DT CLASS="dt-description"><B>Java-initiated unilateral disconnect</B><DD CLASS="dd-description"> is performed by
 invoking the <TT>unilateralDisconnect</TT> method on the <I>RemoteEclipse</I><A NAME="@default310"></A> instance while Java does not have control.<BR>
<BR>
<DT CLASS="dt-description"><B>ECL</B><SUP><B><I>i</I></B></SUP><B>PS</B><SUP><B><I>e</I></B></SUP><B>-initiated multilateral disconnect</B><DD CLASS="dd-description"> is performed on
 the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side by executing a <A HREF="../bips/kernel/externals/remote_disconnect-1.html"><B>remote_disconnect/1</B></A><A NAME="@default311"></A> goal
 while ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> has control, identifying the connection to be closed
 by supplying the peer name.<BR>
<BR>
<DT CLASS="dt-description"><B>ECL</B><SUP><B><I>i</I></B></SUP><B>PS</B><SUP><B><I>e</I></B></SUP><B>-initiated unilateral disconnect</B><DD CLASS="dd-description"> cannot be
 executed by the user, since ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is not
 multi-threaded. However, it may occur in certain urgent situations
 e.g. if the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process is killed while ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> does not
 have control.
</DL>
If an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-initiated disconnect occurs, or the connection is
lost for whatever reason while ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> has control, the Java thread
which handed control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> should throw an <I>EclipseTerminatedException</I>. If either of these happens while Java has
control, the next invocation of a method on the <I>RemoteEclipse</I><A NAME="@default312"></A> should throw an <I>EclipseTerminatedException</I>,
although it is possible that some operations will throw a different
class of <I>IOException</I>. If this should happen it is worth invoking
the <TT>unilateralDisconnect()</TT> method to do a final clean-up.<BR>
<BR>
<A NAME="toc57"></A>
<H3 CLASS="subsection"><A NAME="htoc101">8.7.4</A>&nbsp;&nbsp;Comparison of different Java-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> connection techniques</H3>
<A NAME="sec:ji-compare-connection-classes"></A>
This section should give you some idea of when it is most appropriate
to use each connection class. Figure <A HREF="#fig:ji-connection-classes">8.4</A>
is a UML class diagram showing the most important relationships and
operations of the principal classes and interfaces. <BR>
<BR>
All three classes implement <I>EclipseConnection</I>
<A NAME="@default313"></A>, which provides all the functionality
you would expect during a &#8220;session&#8221; with ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. The <I>EclipseEngine</I> interface <A NAME="@default314"></A> is implemented
when the JVM &#8220;owns&#8221; the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine, and so provides the methods to
access the standard I/O streams. Note that the termination methods are not
in either of the interfaces, but are specific to each class. Furthermore,
the <TT>resume()</TT> method allows <I>RemoteEclipse</I><A NAME="@default315"></A> to explicitly hand
control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, but this operation is not supported by the other two
classes.<BR>
<BR>
To summarise the advantages and disadvantages Table
<A HREF="#tab:ji-feature-comparison">8.2</A> gives an at-a-glance comparison of the
different features of the different connection
classes.<A NAME="@default316"></A><A NAME="@default317"></A><BR>
<BR>
<DIV CLASS="center">
 <BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
 <DIV CLASS="center">
 <IMG SRC="embroot004.gif">
 </DIV>
 <BR>
<BR>
<DIV CLASS="center">Figure 8.4: <A NAME="fig:ji-connection-classes"></A>UML class diagram for different classes connecting Java and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Some convenience methods from <I>EclipseConnection</I> have been omitted.</DIV><BR>
<BR>

 <DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
</DIV>
<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=left NOWRAP>Feature			</TD>
<TD ALIGN=center NOWRAP COLSPAN=3>Java-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> connection class</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>			</TD>
<TD ALIGN=center NOWRAP><I>Embedded</I></TD>
<TD ALIGN=center NOWRAP><I>OutOfProcess</I>	</TD>
<TD ALIGN=center NOWRAP><I>Remote</I></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Implements <I>EclipseConnection</I> interface (allowing <TT>rpc</TT><A NAME="@default318"></A> and queues)</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Implements <I>EclipseEngine</I> interface (allowing access to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stdio streams)</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is in a separate process (with separate memory heap/stack)</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can be on a separate machine from Java</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine can start before/ end after Java virtual machine</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine created/ destroyed from Java</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Efficient transfer of data on queues and <TT>rpc</TT> invocations</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>One ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> can connect to many Java virtual machines using this</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>One Java virtual machine can connect to many ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engines using this</TD>
<TD ALIGN=center NOWRAP>&ndash;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
<TD ALIGN=center NOWRAP>&#8226;</TD>
</TR></TABLE>
</DIV>
<BR>
<BR>
<DIV CLASS="center">Table 8.2: <A NAME="tab:ji-feature-comparison"></A> Feature comparison table for different ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> connection classes</DIV><BR>
<BR>

<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<HR>
<A HREF="embroot047.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
